<HTML><HEAD><TITLE>cursor_N_tuples(++Cursor, -Retrieved, -ResultTuples, -RestResultTuples)</TITLE>
</HEAD><BODY>[ <A HREF="index.html">library(dbi)</A> | <A HREF="../../index.html">Reference Manual</A> | <A HREF="../../fullindex.html">Alphabetic Index</A> ]
<H1>cursor_N_tuples(++Cursor, -Retrieved, -ResultTuples, -RestResultTuples)</H1>
Retrieve  result tuples from the SQL query in the difference list ResultTuples and RestResultTuples.
<DL>
<DT><EM>Cursor</EM></DT>
<DD>A cursor handle
</DD>
<DT><EM>Retrieved</EM></DT>
<DD>Number of result tuples retrieved
</DD>
<DT><EM>ResultTuples</EM></DT>
<DD>Returned difference list (with RestResultTuples) of result tuples
</DD>
<DT><EM>RestResultTuples</EM></DT>
<DD>Tail of returned result tuples
</DD>
</DL>
<H2>Description</H2>
<P>
 This is similar to cursor_all_tuples/4 except it works on difference list.
 It is designed to efficiently retrieve a buffer full of tuples for DBMS
 that support the retrieval of multiple tuples in its API. Otherwise, all
 the remaining tuples are retrieved one by one and the ResultTuples list
 constructed. Retrieved is unified with the number of retrieved result
 tuples. If no tuples match the query, Retrieved will be 0. Each element
 of the list is a single result tuple. Cursor is a cursor previously
 created with session_sql_query/4 or session_sql_prepare_query/5. Each
 tuple in ResultTuples is a structure with the same name and arity as
 defined by the tuple template when the cursor was created. The predicate
 converts the result to the type specified in the template, except that
 NULL values are returned as variables.
</P><P>
 If the SQL query have not yet been executed, and it contains no
 parameters, then the SQL query will first be executed before retrieving
 the results.
</P><P>
 MySQL specific note: MySQL does not support the retrieval of multiple
 tuples in one go, so for MySQL, this predicate is essentially equivalent
 to retrieving the results one by one.

<H3>Exceptions</H3>
<DL>
<DT><EM>(5) type error </EM>
<DD>Cursor is not a valid cursor handle
<DT><EM>(5) type error </EM>
<DD>Unable to convert tuple result to ECLiPSe type
<DT><EM>(dbi_error) </EM>
<DD>Error from DBMS while executing SQL associated with Cursor.
<DT><EM>(dbi_error) </EM>
<DD>Error from DBMS while fetching result
<DT><EM>(dbi_not_query) </EM>
<DD>The SQL associated with Cursor is not a query and so cannot return results.
</DL>
<H2>See Also</H2>
<A HREF="../../lib/dbi/session_sql_query-4.html">session_sql_query / 4</A>, <A HREF="../../lib/dbi/session_sql_prepare_query-5.html">session_sql_prepare_query / 5</A>, <A HREF="../../lib/dbi/cursor_next_tuple-2.html">cursor_next_tuple / 2</A>, <A HREF="../../lib/dbi/cursor_all_tuples-2.html">cursor_all_tuples / 2</A>
</BODY></HTML>
